Cream of the Crop 1

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / MOUSPP30.ARJ / MOUSE.DOC < prev next >

Wrap

Text File | 1992-02-21 | 41KB | 951 lines

Mouse++ Version 3.0 Copyright (c)1992 by Carl Moreland 02/21/92 ----------------------------------------------------------------------- What is Mouse++ ? Mouse++ is a mouse interface class for Borland C++ or TurboC++. It consists of three source files: mouse.h header file for Mouse++ mouse.cpp source code for Mouse++ cursor.h text & graphic cursor definitions A demonstration of most of the functions for both text mode and gra- phics (EGA/VGA) mode is contained in micedemo.cpp. To incorporate the mouse routines in your program, simply add mouse.cpp to your project or make file, and #include mouse.h in any module that calls a mouse function. An instance of the Mouse class (there can only be ONE instance) is declared as extern in mouse.h, so any file that #includes mouse.h will automatically have access to the mouse. You should NOT declare an instance of the Mouse class in any part of your program. If you intend to change the mouse cursor, then you also need to #include cursor.h. ----------------------------------------------------------------------- Using the Mouse Class When you link the mouse code into your program, an instance of the mouse class is declared: Mouse mouse; The constructor Mouse::Mouse() calls the mouse driver reset function (all mouse driver functions are called via interrupt 33h) and initia- lizes the flags exists, enabled, and visible. exists is set to 1 if a mouse was found and should be checked first. All other mouse class functions check exists before issuing interrupt 33h calls and abort if it is zero. enabled is initially zero meaning the mouse is disabled, and visible is used by Show() and Hide() to keep track of the cursor visibility. An example of initializing the mouse is: #include "mouse.h" main() { if(mouse.Exists()) // check for mouse { mouse.Enable(); // enable the mouse mouse.Show(); // display the cursor ... } } Again, including mouse.h automatically creates an instance of the class, so all you have to do is start using it. Once the mouse is initialized, it may be necessary to set some parameters based on what video mode is being used. Strangely, the mouse driver uses pixel coordinates for both text and graphics mode, with (0,0) being the upper left hand corner of the screen, and (639,199) being the default lower right hand corner. This would be correct for CGA graphics mode, and for normal 80x25 text mode, this means that each character cell is treated as an 8x8 pixel array. If you are program- ming for the EGA or VGA as is the norm these days, you will want to change the y-limit of 199 for high resolution graphics and 43 or 50 line text modes. Failure to do this means that the mouse cursor will not move below the 200th line in graphics mode, or the 25th row in text mode. (Older mouse drivers might not support more than 200 lines. If this is the case, you will need to update your mouse driver.) For 640x480 VGA graphics, you need to set the y-limit to (0,479) by calling yLimit(0,479). For 43 or 50 line text mode, the mouse driver still treats each character cell as an 8x8 pixel array, so you need to set the y-limit to (0,349) or (0,399), respectively. Since the default width of 640 pixels is correct for most video modes, xLimit() is only necessary when using SuperVGA graphics. Both xLimit() and yLimit() can also be used to limit the mouse cursor to a small portion of the screen, such as a menu. You may want to use a mouse cursor other than the default cur- sor. To do this, call the function SetGraphicsCursor() or SetText- Cursor() with the appropriate cursor name. Many programs (especially graphics) will use several different cursors depending on the location of the mouse (such as an arrow for menus and an i-beam for text) or the particular function being processed (such as an hourglass for wait). Several cursors are predefined in the file cursor.h. To use them, sim- ply include this header file in whatever module changes the cursor. For more information on cursors, see the Mouse Cursors section. Finally, you may want to set the motion parameters, which in- clude the mickey-to-pixel ratio and the double-speed threshold. The mickey-to-pixel ratio is set by MickToPix() and defines how many mic- keys it takes to move the mouse 8 pixels. (A mickey is single count of mouse motion. Most mice are 200 "dots-per-inch", which meansthat one inch of movement results in 200 mickeys.) If both the x and y parame- ters are set to 8, then there will be a one-to-one correlation between mouse motion and cursor motion. The default values are 8 in the hori- zontal direction and 16 for the vertical. The vertical value of 16 means the mouse must be moved twice as far vertically as horizontally to get the same cursor movement. This is fine for text mode where the equivalent screen resolution of 640x200 results in an equivalent pixel aspect ratio of 2.4-to-1. In EGA/VGA graphics mode the y-direction will seem noticeably slower, particularly for 640x480 which has an equivalent pixel aspect ratio of 1-to-1. A vertical ratio of 8 will cure this. The lower the ratio, the farther the cursor will move for a given mouse movement. Setting either ratio lower than 8 means that the cursor cannot be located on every pixel. For example, setting the ra- tio to 4 will cause the cursor to move 2 pixels for every mickey. The double-speed threshold is set by a call to SetSpeedThreshold(). When the speed of the mouse (in mickeys per second) exceeds the speed para- meter passed to SetSpeedThreshold(), the motion speed of the cursor will double. A complete initialization might look like this: #include "mouse.h" #include "cursor.h" main() { { initialize screen }; if(mouse.Exists()) { mouse.SetGraphicsCursor(cross); mouse.yLimit(0,479); // VGA 640x480 mouse.MickToPix(8,8); mouse.SetSpeedThreshold(32); mouse.Enable(); mouse.Show(); ... } } The mouse should be reset before your program terminates so that the calling program does not inherit any strange parameters. This is particularly true of the event handler. Because it is an interrupt routine, failure to reset the mouse could lead to a system crash if the handler is still pointing to the address of what used to be your hand- ler routine. The destructor Mouse::~Mouse() first resets the mouse status by calling function 00h, and then restores the original event handler with function 14h. ----------------------------------------------------------------------- Reading the Mouse Most of the standard mouse functions stuff any return values directly into the class variables and have a return type void. You can then use the appropriate inline function to read the required private variable. To check for the mouse position, for instance, you would call Position() followed by either xPos() or yPos(), or both, such as: for(;;) { mouse.Position(); if(mouse.xPos() > 320 || mouse.yPos() > 100) do_something(); } This method has the advantage of capturing both the x and y positions with a single function call, and those variables can then be read at your leisure. However, we generally don't care where the mouse is located unless a button event that we are looking for has occurred. Position() also returns the status of the mouse buttons, so we can also check them: for(;;) { mouse.Position(); if(mouse.LB_Dn()) // check for left button down { if(mouse.xPos() > 320 || mouse.yPos() > 100) do_something(); } else do_something_else(); } This loop will continuously check to see if the left button has been pressed. If the do_something_else() code is slow then there is a pos- sibility that a button press could be missed since Position() returns the real-time status of the mouse. That is, during execution of the do_something_else() code, the mouse button could be pressed and re- leased and Position() would not capture it. The functions Pressed() and Released() are best suited for checking for a button event because they will return the button status since the last time they were called. For example, this code for(;;) { if(mouse.Pressed(LEFTBUTTON)) { if(mouse.xPos() > 320 || mouse.yPos() > 100) do_something(); } else do_something_else(); } is guaranteed to capture a button press even if the do_something_else() code is slow to execute. Since Pressed() and Released() also return the cursor position, a separate call to Position() is not necessary. In using the mouse, it is often necessary to know if the cursor is located within a certain area of the screen. For example, in a menu interface, you want to know if the cursor is located on a menu selec- tion when a mouse button is clicked. The function InBox() adds this capability. The parameters passed describe the upper left and lower right corners of the box. The return value is 1 if the cursor is in the box, 0 if not. Therefore, the code if(mouse.InBox(40,40,100,100)) will be true if the mouse cursor is in a box with corners (40,40) and (100,100). Like other mouse functions, the coordinates are pixels, even if the screen is in text mode. In some cases you may want to hide the cursor if it falls in- side a certain area. The mouse driver provides such a function which, in my opinion, has two drawbacks. Function 10h defines an exclusion window in which the mouse cursor will turn itself off. However, the programmer must then manually turn the cursor back on once it is out- side the exclusion area, and this requires continuously checking the mouse position, such as: for(;;) { mouse.Exclude(40,40,100,100); do_some_processing(); if(!mouse.InBox(40,40,100,100)) mouse.show(); } The other problem with function 10h is that it only looks at the hot spot when checking the cursor's position, so part of the cursor could enter the exclusion area before the hot spot. The whole point of de- fining an exclusion area is to turn the cursor off if it enters the defined area. The Mouse++ Exclude() function is based on the InBox() function, taking into account the hot spot location and cursor visi- bility. Finally, if your program is performing a time-consuming task in which mouse input is not needed, you may want to disable the mouse. If the mouse is not disabled, the user might become frustrated with a mouse that does not respond, and the event buffer could become filled with useless events. Calling the function Disable() will turn the mouse off and disable the interrupt handler. The mouse and interrupt handler are re-enabled with the next call to Enable(), although the mouse cursor must be turned on with an explicit call to Show(): ... mouse.Disable(); do_some_long_processing(); mouse.Enable(); mouse.Show(); ... ----------------------------------------------------------------------- Mouse Cursors SetGraphicsCursor() sets the graphics cursor shape. The cursor is initially set to the familiar upper left pointing arrow by the mouse driver. A graphics cursor is 16x16 pixels in size and moves in single pixel increments. It is defined by a screen mask (background), an over- lying cursor mask (foreground), and a hot spot. Since the cursor is 16x16 pixels, a hot spot must be defined so that a unique pixel posi- tion can be determined for the cursor. The hot spot has x and y values with valid ranges of 0 to 15. The two masks determine how the screen will appear where the cursor is located. The screen mask is first ANDed with the screen pixels, and the cursor mask is then XORed with the resulting screen. If a screen mask bit is 0 it will set the underlying screen pixel to 0 (black), and if the screen mask bit is 1 the pixel color will not change. A cursor mask bit of 0 does nothing, and a cursor mask bit of 1 will invert the underlying pixel color. Since the masks have only values of 1 or 0 for each pixel location, but each pixel can have a color, you cannot achieve complete control of the cursor color. The two basic choices are a black and white cursor where the screen mask bits are 0, or a cursor that inverts the screen colors where the screen mask bits are 1. Figure 1 shows the default cursor as an example. The screen mask alone will set the screen pixels to black for the bits that are 0, creating a black arrow. The cursor mask bits that are 1 will then in- vert the screen color, meaning black will become white. If you lay the cursor mask directly over the screen mask, you will notice that the screen mask arrow extends one pixel beyond the cursor mask arrow. Be- cause a screen mask bit 0 will create a black background for the cursor mask, this has the effect of putting a one pixel black border around the cursor. The reason for doing this is to make the cursor visible even where the screen is white. Making the screen mask bits all 1's so that the cursor XOR's with the underlying screen is useful in creating a CAD cursor (such as a "+" or a "x") that must be one pixel wide. The best way to get a better understanding of the graphics cursor is to try some out. cursor.h defines several graphics cursors. ----------------------------------------------------------------------- 0011111111111111 0000000000000000 0001111111111111 0100000000000000 0000111111111111 0110000000000000 0000011111111111 0111000000000000 0000001111111111 0111100000000000 0000000111111111 0111110000000000 0000000011111111 0111111000000000 0000000001111111 0111111100000000 0000000000111111 0111111110000000 0000000000011111 0111111111000000 0000000111111111 0111110000000000 0001000011111111 0100011000000000 0011000011111111 0000011000000000 1111100001111111 0000001100000000 1111100001111111 0000001100000000 1111110000111111 0000000110000000 Screen Mask Cursor Mask Figure 1: Example graphics cursor ----------------------------------------------------------------------- The graphics mask pair are defined together in a single array of type unsigned integer. For clarity, comment fields were added in cursor.h to show what the masks will actually produce. This is helpful not only in identifying what a cursor looks like, but also in designing new cursors. Since the graphics cursor is a 16x16 pixel image, it also requires a hot spot for determining the exact position of the mouse. The hot spot and the mask array are combined in the structure GraphicsCursor (defined in mouse.h), which must be static. The cursor structure can then be passed as a unit to SetGraphicsCursor(). SetTextCursor() sets the text cursor type and shape. There are two cursor types in text mode. The hardware cursor places the normal video cursor (the cursor you see even without a mouse) under the con- trol of the mouse. The software cursor is independent of the video cursor and behaves similarly to the graphics cursor. The software cur- sor is used in most applications so that the user is presented with the normal video cursor for typing and a mouse cursor for menu selection. The cursor type - 0 for software, 1 for hardware - is part of the TextCursor structure. Like the graphics cursor, the text software cursor also re- quires a screen and cursor mask, but no hot spot since the cursor al- ways takes up a whole character cell, regardless of where the mouse cursor is actually positioned in that cell. (If a hardware cursor is implemented, the starting and ending scan lines for the cursor are required.) The two masks operate only on a character cell, not a 16x16 pixel array. Each cell consists of a one-byte character value and a one-byte character attribute (which sets the foreground and background colors), so the masks must each be two bytes long. The upper byte masks the attribute, and the lower byte masks the character. Like the graphics masks, the screen mask is XORed with the underlying character cell, and the cursor mask is ANDed with the resulting value. The dif- ference is that in text mode, both the character value and its color can be changed, whereas in graphics mode, the pixel colors cannot be controlled. To get a better understanding of what the masks will do, we need to look at an example of a screen character: 6B24h = 0110 1011 0010 0100 b |--- ---- --------- | | | |__ character value | | |__________ foreground color | |______________ background color |________________ blinking bit (1=blinking) This value will display a '$' (24h) with a background color of brown (06h) and a foreground color of lightcyan (0Bh = 11). With the text cursor, we can mask each bit of the character and attribute, so not only can we set the mouse cursor character, but we can also control the foreground and background colors (and even blinking). The cursor masks default to a reverse box, which is Screen Mask = 77FFh = 0111 0111 1111 1111 b Cursor Mask = 7700h = 0111 0111 0000 0000 b The first byte of the screen mask, 77h in this example, is ANDed with the underlying characters attribute. The first 7h is ANDed with the background color so that all colors but the blinking bit are passed through. Masking the blinking bit to 0 will allow the mouse cursor to rest on a blinking character without itself blinking. The second 7h is ANDed with the foreground color so that those colors are also passed, except that the high intensity colors will be converted to low inten- sity. The FFh also passes the screen character. In the cursor mask, the 77h will invert both the foreground and background colors, while the 00h creates an "empty" character, which is a character cell with nothing in it (a box). If you want to create a cursor with a particular character and color, you would set the screen mask to 0000h and the cursor mask to whatever color and character values desired. For example, Screen Mask = 0000h = 0000 0000 0000 0000b Cursor Mask = 0F23h = 0000 1111 0010 0011b will set the cursor character to a '#' with a background color of black and a foreground color of white. More complex combinations are possi- ble, such as setting the cursor's foreground color to a constant value but allowing the screen's background color to show through. Again, the best way to understand it is to try it, and cursor.h defines several text cursors. ----------------------------------------------------------------------- The Event Handler There is another way to capture mouse events. The mouse event handler is similar to a TSR program in that it can be set up to capture events in background. The handler can be set to trigger off any combi- nation of mouse events (Table 1), and can then execute any user code, providing it does not issue a DOS or I/O call. However, since the main program is suspended during the event handler execution, the handler code should be fast so it does not to noticeably slow down the main pro- gram. When an event occurs, certain mouse information is automatically placed in the registers for the handler to use. The routine Save() can be used to stuff these parameters into the Mouse class for later use. Any event handler routines you write must be declared as an interrupt type and terminate with a far return. The macro EventExit() provides the proper exit code and should be the last statement in the handler function: void interrupt my_handler() { mouse.Save(); do_something(); EventExit(); } Installing an event handler is accomplished with the function InstallHandler(): #include "mouse.h" void interrupt my_handler(); main() { unsigned char eventmask = LB_PRESSED || LB_RELEASED; if(mouse.Exists()) { mouse.InstallHandler(eventmask, myhandler); mouse.Show(); ... } } eventmask determines which mouse events will trigger the event handler. In the example above, the handler will execute whenever the left button is pressed or released. Because the event handler should be kept as small as possible, you normally only want to call Save() for storing the mouse information and then exit. The mouse class provides such a handler by default if you do not specify a handler function name in the call to InstallHandler(): main() { if(mouse.Exists()) { mouse.InstallHandler(LB_PRESSED || LB_RELEASED); mouse.Show(); ... } } There might be some cases where you want the handler to do more, such as when the program is waiting for user input and not doing much other processing. In such cases you may want to load different handlers, depending on what the program is doing. A more functional handler can be loaded for pulldown menus, for instance, and a bare-bones handler (or none at all) can be installed in speed critical areas where the mouse has little use. The Save() function called by the event handler stores the mouse information in a buffer instead of writing it directly into the class. This allows events to be captured even while your program is busy doing something else. (The keyboard has a similar buffer that provides type-ahead capability.) To get the event information out of the buffer, you must call the function GetEvent(): for(;;) { mouse.GetEvent(); // get an event from the buffer if(mouse.LB_Dn()) // check for left button down { if(mouse.xPos() > 320 || mouse.yPos() > 100) do_something(); } else do_something_else(); } Properly used, event handlers can add a whole new dimension to a mouse driven interface. However, there are some pitfalls to avoid. If you set the event mask to trigger on mouse movement, then the hand- ler will execute quite often (every time the mouse is moved) and could noticeably slow program execution during periods of heavy computation. Usually, the only reason to trigger on movement is to update a motion counter such as in the demo program, or to have cursors that dynami- cally change depending on the cursor position such as in a GUI. As mentioned before, the handler should not issue a DOS, ROM, or I/O call. The handler, like a TSR, is an interrupt routine that runs while the main DOS program is suspended. DOS is not a re-entrant operating sys- tem and issuing such a call will usually crash the system. Also, some standard C library routines make use of these system functions (such as printf()), so often the only way of finding out is by trial and reboot. ----------------------------------------------------------------------- 0x01 MOUSE_MOVED 0x02 LB_PRESSED 0x04 LB_RELEASED 0x08 RB_PRESSED 0x10 RB_RELEASED 0x20 CB_PRESSED 0x40 CB_RELEASED Table 1: Mouse events ----------------------------------------------------------------------- A Demonstration micedemo.cpp is a demo program that utilizes most of the mouse functions described. main() installs the event handler, runs a text mode demo, and a graphics mode demo. The event mask is FFh which will trigger the handler on any mouse event. Since that includes mouse movement, the default handler that only calls Save() is used to store the parameters and keep execution time to a minimum. Both demos (textdemo() and graphicdemo()) call a function that draws the screen and another that processes mouse events. textscreen() assumes a color video card and draws a screen with eight different characters and colors to demonstrate how the cursor masks work. Notice that the loop that draws the screen actually writes 50 lines of video even though the demo starts out with 25 lines. A graphical represen- tation of a three-button mouse is drawn to show the cursor position and button status. After calling textscreen(), textdemo() prints the infor- mation from the mouse.Info structure to the screen. The mouse y-limit is set to full screen (25 lines, which is the default) and the cursor is turned on with Show(). nexttdemo() is the processing loop for text mode and is called with the name of text cursor structure and a title string. nexttdemo() is called with several different cursors and also for 43/50 line mode. nexttdemo() first sets the text cursor and prints the title string. It then runs a loop that process mouse events. A counter that shows the mouse position calls xPos() and yPos() which read variables that are continuously updated by the event handler via GetEvent(). Button status is also checked and displayed. Released() is called to check for a left button release event which will terminate the loop if the cursor is inside the [Next] box at the time of release. The loop will also be terminated if the left button is double-clicked anywhere on the screen. If the right button is double-clicked, the mouse is disabled until any keyboard key is pressed. Pressing the <Ctrl> key and the left button will set the global flag "done" which exits the rest of the text demo and proceeds with the graphics demo. graphicdemo() works the same way as textdemo(). In addition to trying several cursors, it also tests different mickey-to-pixel ratios. Notice that the ratio of 2 for the jet cursor will cause the cursor to locate on every fourth pixel as it moves across the screen. graphicscreen() paints several background colors as well as black and white boxes in the center. These boxes demonstrate the use of the cursor border created by the screen mask. A graphical representation of a three-button mouse is again drawn to show the cursor position and button status. nextgdemo() sets the graphics cursor and then processes mouse events, checking the position and button status. The variables LBDN, CBDN, and RBDN are used to compare the cur- rent button status against the previous button status. The color of the screen buttons are then toggled if any button status has changed. (This method is used to avoid screen paints in every pass through the loop if the button status has not changed. This is not necessary in text mode because screen writes are much faster.) Buttons are checked for multi-clicks (up to four) and the color of the screen buttons will reflect this. Finally, we check for a left button release and see if the cursor is in the [Next] box, a left button triple-click, and a <Ctrl>-left button, and exit if so. ----------------------------------------------------------------------- The Mouse++ Functions ----------------------------------------------------------------------- Mouse::Exists() Syntax: unsigned char Exists(void) Description: Returns the value of an internal flag that is set by the Mouse constructor. Return Value: 1 if a mouse was found, 0 otherwise. ----------------------------------------------------------------------- Mouse::Visible() Syntax: unsigned char Visible(void) Description: Returns the status of the cursor visibility. Return Value: 1 if the cursor is visible, 0 otherwise. ----------------------------------------------------------------------- Mouse::Buttons() Syntax: unsigned char Buttons(void) Description: Returns the number of buttons for the mouse Return Value: 2 for a 2-button mouse, 3 for a 3-button mouse. ----------------------------------------------------------------------- Mouse::Button() Syntax: unsigned char Button(void) Description: Returns the status of the mouse buttons and shift keys that is stored internal to the Mouse class. Call Position() before using this function to insure an accurate value, or when using the event handler call GetEvent(). Return Value: A mask corresponding to the status of the mouse buttons and the shift keys (down=1, up=0): ------------------------------------------------------- 0x01 Left button 0x02 Right button 0x04 Center button 0x08 Either shift key 0x10 Right shift key 0x20 Left shift key 0x40 Alt key 0x80 Ctrl key ----------------------------------------------------------------------- Mouse::Enable() Syntax: void Enable(void) Description: Enables the mouse. This function must be called before the mouse can be used for the first time, or after a call to Disable(). A separate call to Show() is neces- sary to display the cursor. Return Value: None. ----------------------------------------------------------------------- Mouse::Disable() Syntax: void Disable(void) Description: Disables the mouse and hides the cursor. If an event handler has been installed, it is disabled and the event buffer and multi-click buffer are cleared. Return Value: None. ----------------------------------------------------------------------- Mouse::Show() Syntax: void Show(void) Description: Turns on the mouse cursor. Return Value: None. Sets the internal visible flag to 1. ----------------------------------------------------------------------- Mouse::Hide() Syntax: void Hide(void) Description: Turns off the mouse cursor. All other mouse functions will continue to operate. You should hide the cursor prior to any screen writes to avoid having the mouse restore an incorrect background. Return Value: None. Sets the internal visible flag to 0. ----------------------------------------------------------------------- Mouse::Position() Syntax: void Position(void) Description: Reads the cursor position and saves the coordinates in internal variables. Use xPos() & yPos() to read the internal variables. This function is not intended for use with the event handler. Return Value: None. Sets internal class position variables and button status. ----------------------------------------------------------------------- Mouse::xPos() Syntax: int xPos(void) Description: Returns the x-position of the mouse cursor that is stored internal to the Mouse class. Call Position() before using this function to insure an accurate value, or when using the event handler call GetEvent(). Return Value: An integer that corresponds to the pixel location of the cursor, even if the screen is in text mode. ----------------------------------------------------------------------- Mouse::yPos() Syntax: int yPos(void) Description: Returns the y-position of the mouse cursor that is stored internal to the Mouse class. Call Position() before using this function to insure an accurate value, or when using the event handler call GetEvent(). Return Value: An integer that corresponds to the pixel location of the cursor, even if the screen is in text mode. ----------------------------------------------------------------------- Mouse::Motion() Syntax: void Motion(void) Description: Reads the internal motion counters which give the dis- tance (in mickeys) the mouse has moved since the last call to this function, and stores the values in class variables. Use xCount() & yCount() to read these vari- ables. This function is not intended for use with the event handler. Return Value: None. ----------------------------------------------------------------------- Mouse::xCount() Syntax: int xCount(void) Description: Returns the distance the mouse has moved in the x- direction. The distance is in mickeys, which may or may not be the same as pixels, depending on the mickey-to- pixel ratio. This function is useful for seeing if the mouse has moved. Return Value: An integer that corresponds to the x distance in mic- keys, regardless of screen mode. ----------------------------------------------------------------------- Mouse::yCount() Syntax: int yCount(void) Description: Returns the distance the mouse has moved in the y- direction. The distance is in mickeys, which may or may not be the same as pixels, depending on the mickey-to- pixel ratio. This function is useful for seeing if the mouse has moved. Return Value: An integer that corresponds to the y distance in mic- keys, regardless of screen mode. ----------------------------------------------------------------------- Mouse::Move() Syntax: void Move(int x, int y) Description: Moves the cursor to a new position. x & y must be pixel coordinates even if the screen is in text mode. Return Value: None. ----------------------------------------------------------------------- Mouse::Pressed() Syntax: int Pressed(int mbutton) Description: In manual mode, this checks to see if mbutton has been pressed since the last call to this command. In event driven mode, this checks to see if the current event was triggered by mbutton pressed. mbutton can be 0 (LEFTBUTTON), 1 (RIGHTBUTTON), or 2 (CENTERBUTTON). Return Value: 1 if mbutton has a pressed event, 0 otherwise. ----------------------------------------------------------------------- Mouse::Released() Syntax: int Released(int mbutton) Description: In manual mode, this checks to see if mbutton has been released since the last call to this command. In event driven mode, this checks to see if the current event was triggered by mbutton released. mbutton can be 0 (LEFTBUTTON), 1 (RIGHTBUTTON), or 2 (CENTERBUTTON). Return Value: 1 if mbutton has a released event, 0 otherwise. ----------------------------------------------------------------------- Mouse::LB_Dn() Syntax: unsigned char LB_Dn(void) Description: Returns the status of the left button. Return Value: 1 if the left button is pressed, 0 otherwise. ----------------------------------------------------------------------- Mouse::RB_Dn() Syntax: unsigned char RB_Dn(void) Description: Returns the status of the right button. Return Value: 1 if the right button is pressed, 0 otherwise. ----------------------------------------------------------------------- Mouse::CB_Dn() Syntax: unsigned char CB_Dn(void) Description: Returns the status of the center button. Return Value: 1 if the center button is pressed, 0 otherwise. ----------------------------------------------------------------------- Mouse::xLimit() Syntax: void xLimit(int min, int max) Description: Sets the limit that the cursor can move in the x- direction. min & max must be pixel values even if the screen is in text mode. Return Value: None. ----------------------------------------------------------------------- Mouse::yLimit() Syntax: void yLimit(int min, int max) Description: Sets the limit that the cursor can move in the y- direction. min & max must be pixel values even if the screen is in text mode. Return Value: None. ----------------------------------------------------------------------- Mouse::SetTextCursor() Syntax: void SetTextCursor(TextCursor& cursor) Description: Sets the text cursor as described by the TextCursor structure. Return Value: None. ----------------------------------------------------------------------- Mouse::SetGraphicsCursor() Syntax: void SetGraphicsCursor(GraphicsCursor& cursor) Description: Sets the graphics cursor as described by the GraphicsCursor structure. Return Value: None. ----------------------------------------------------------------------- Mouse::MickToPix() Syntax: void MickToPix(int horiz, int vert) Description: Sets the mickey-to-pixel ratio. A mickey is a motion signal sent by the mouse and occurs every 1/200th inch for most mice. horiz passes the number of mickeys re- quired for an 8 pixel horizontal movement, and vert passes the number of mickeys required for an 8 pixel vertical movement. The constructor sets these to 8 and 16, respectively. Return Value: None. ----------------------------------------------------------------------- Mouse::SetSpeedThreshold() Syntax: void SetSpeedThreshold(unsigned speed) Description: Sets the threshold at which the cursor speed doubles. speed is in mickeys-per-second and defaults to 64. Supposedly, this function is only available for Logi- tech mice. Return Value: None. ----------------------------------------------------------------------- Mouse::SetClickThreshold() Syntax: void SetClickThreshold(unsigned time) Description: Sets the threshold at which sequential clicks are regi- stered as multi-clicks. time is in milliseconds and de- faults to 250. Return Value: None. ----------------------------------------------------------------------- Mouse::MultiClick() Syntax: int MultiClick(int mbutton) Description: Checks for multi-clicks of button mbutton. mbutton can be 0 (LEFTBUTTON), 1 (RIGHTBUTTON), or 2 (CENTERBUTTON). Return Value: Current number of multi-clicks. ----------------------------------------------------------------------- Mouse::DoubleClick() Syntax: int DoubleClick(int mbutton) Description: Checks for double-clicks of button mbutton. mbutton can be 0 (LEFTBUTTON), 1 (RIGHTBUTTON), or 2 (CENTERBUTTON). Return Value: 1 if mbutton has been double-clicked, 0 otherwise. ----------------------------------------------------------------------- Mouse::ClearClick() Syntax: void ClearClick(int mbutton) Description: Resets the multi-click status of mbutton. mbutton can be 0 (LEFTBUTTON), 1 (RIGHTBUTTON), or 2 (CENTERBUTTON). Return Value: None. ----------------------------------------------------------------------- Mouse::InBox() Syntax: int InBox(int left, int top, int right, int bottom) Description: Checks if the mouse cursor is located within a rec- tangle. Rectangle limits should be in pixels regardless of screen mode. Return Value: 1 if the cursor is in the rectangle, 0 otherwise. ----------------------------------------------------------------------- Mouse::Exclude() Syntax: void Exclude(int left, int top, int right, int bottom) Description: Sets up an exclusion area in which the mouse cursor automatically turns itself off. This is not the same as the exclude function that is built into the mouse, and must be continuously called in a loop. Rectangle limits should be in pixels regardless of screen mode. Return Value: None. ----------------------------------------------------------------------- Mouse::InstallHandler() Syntax: void InstallHandler(unsigned mask, void interrupt (*fn)(void)) Description: Installs an interrupt handler function. This function is automatically run whenever an event occurs that is included in the mask. The mouse driver loads the CPU registers with mouse information before calling the function. Therefore, the first action should be to save this information to an event buffer, which can be accom- plished by calling the Save() function. The remaining function code should be kept to a minimum, and the func- tion MUST be terminated with the EventExit() macro. The mask bits are described in Table X. If a function poin- ter is not passed in the parameter list, then the de- fault handler MouseHandler() will be used. Return Value: None. ----------------------------------------------------------------------- Mouse::Save() Syntax: void Save(int event, int button, int x, int y, int xcount, int ycount) Description: Stores the passed parameters in the event buffer. This should be the first function called from an event hand- ler routine. See the default handler MouseHandler() for details. Return Value: None. ----------------------------------------------------------------------- Mouse::GetEvent Syntax: void GetEvent(void) Description: Gets the next event from the event buffer and loads the parameters into class variables. Return Value: None. ----------------------------------------------------------------------- Mouse::ClearEvent Syntax: void ClearEvent(void) Description: Clears the current event from the internal class varia- bles. Return Value: None. ----------------------------------------------------------------------- Mouse::ClearBuffer() Syntax: void ClearBuffer(void) Description: Clears the event buffer. Return Value: None. ----------------------------------------------------------------------- References 1. Kent Porter, "Mouse Mysteries, Part I: Text", Turbo Technix, Vol. 1, No. 4, pp. 52-67, May/June 1988. 2. Kent Porter, "Mouse Mysteries, Part II: Graphics", Turbo Technix, Vol. 1, No. 5, pp. 42-53, July/August 1988. 3. Terry Dettmann, DOS Programmers Reference, Part V: Reference, Mouse Functions, pp. 717-739, Que, 1989. 4. Ralf Brown, Interrupt List, Release 90.3, July 15, 1990. This is available on the Public Domain as INTER390.